EZhelp Reference, EZcomp compiler (C) Copyright 1990, Brain Child Systems. All rights reserved. -------------------------------------------------------------------------- {{ What's EZhelp?, 1,1,0 }} ........................................................................ I N T R O D U C T I O N T O E Z h e l p R e f e r e n c e version 1.2 A ShareWare reference tool (C) Copyright Brain Child Systems, 1990 All rights reserved ........................................................................ Hello! EZhelp is a shareware package designed as a tool for writers or programmers who need a basic help system to use stand-alone or call from existing software, or to use as an on-line reference. You can easily create a window driven help system with new or existing texts, and registered users may distribute them with EZhelp free of charge. This reference guide is driven by EZhelp, and describes how to set up your own text files and for in-house use or distribution. Take a moment to read the help topics and move through the different menus. Any suggestions you have for the program are welcome. There are many possible features that could be added, and this will depend on what you ask for. If you try the program and have an opinion, drop us a line! EZhelp consists of three programs: EZcomp.EXE - A text compiler program that creates an index on help reference files. This index file describes where topics begin and end within the text. EZhelp.EXE - The program that uses the help file and the index created with the compiler to drive the windows and text display. EZsetup.EXE - A utility program that creates a default options file for use by EZhelp at runtime. You will need a text editor or word processor to create your text files with. There are a few issues to be aware of when using a word processor. For more information, select the "Entering text" menu. You will also be more successful with this package if you follow the hints on organizing your topics. More information can be found in the "Forming Outline" menu. EZhelp features:  quick text compiler with optional topic sorting, reference report, error messages  pop-up menus  choice of line style  choice of colors on five screen components  manual/automatic text window sizing  optional page number display  choice of PageUp/PageDn/Escape messages  display text at top or bottom of screen  start at any menu level  jump directly to any help topic  1 free update {{ 3 easy steps, 1,2,0 }}  3 easy steps There are 3 steps to setting up your own help reference system: 1) Writing the reference help text - Forming an outline, creating topic definitions, and entering the text 2) Compiling text - Compiling the text using EZcomp to create the text index 3) Using EZhelp - Calling the program with a choice of startup options and/or default data created by EZsetup.exe {{ Writing text, 1,3,2 }} .... menu 2 is next .... {{ Compiling text, 1,4,3 }} .... menu 3 is next .... {{ Using EZhelp, 1,5,4 }} .... menu 4 is next .... {{ Using EZsetup, 1,6,0 }}  Using EZsetup EZsetup is a utility that creates a data file of startup options used by EZhelp Reference at runtime. The options that can be saved in the data file are:  Title color  1st letter auto selection  Letter color  Automatic window sizing  Window color  Page number display  Border color  Error display  Hilite color  Customized page up string  Border style  Customized page down string  Customized exit string  Help window anchor (top or bottom) Some of the startup data options can be overridden from the command line when EZhelp is started. For more information on command line parameters, see Using EZhelp, Command line. {{ Registering, 1,7,0 }}  Registering EZhelp EZhelp is a shareware product, and may be used for a reasonable trial period free of charge. What defines a reasonable trial period? You may evaluate the package for 30 days, which should be enough time to decide if you would like to continue using it. The basic registration fee is $25. This fee includes a diskette with all EZhelp executable files, including the compiler and setup utility, and a user's guide on the diskette. When an update becomes available, registered users will be notified. One free update will be provided, less media and postage costs. To register EZhelp, print out a copy of the file "order.frm" with this DOS command: COPY ORDER.FRM > PRN 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴커 � R e g i s t r a t i o n F o r m / U s e r P r o f i l e � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 � Name Computer __________________ Brain Child Systems � � Company Application to use P.O. Box 3882 � � Address EZhelp (if any) ___________ Austin, TX 78764 � � City State ZIP EZhelp version ____________ � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 � � � � � Twenty percent of each registration fee will be donated to � � a non-profit, charitable organization. � � � � � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 � Basic Registration fee... 25.00 Laser printed guide... 10.00 � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴켸 {{ ---------------, 1,8,0 }} {{ Charityware?, 1,9,0 }} ........................................................................ Charityware 컴컴컴컴컴컴컴컴컴컴� Twenty percent of each registration fee received for this package will be donated to charity. This pledge extends for the lifetime of this package and any subsequent versions. The concept of charityware is something that should be explored. This package is fundamentally a shareware package, with voluntary registration and trial use. No obligation on your part is implied with its use during a reasonable trial period. The basic trust embedded in the shareware concept can have a double benefit with the Charityware concept - not only have you done your part to promote shareware and shareware authors, you also have made a charitable contribution that counts. If you have any questions or comments on the Charityware concept, please contact us. We have more information of interest available to shareware authors and corporate donors. ........................................................................ {{ Forming outline, 2,1,0 }}  Forming an outline of the text Writing an outline is the essential first step to creating the reference. It will help to begin with the most general subjects, and narrow the subjects into sub-topics and further sub-topics. The outline itself should have no more than eight levels of sub-topics. A typical printed reference guide has a table of contents and body of text, and an optional index. An EZHelp text file contains the same elements. The items in the outline become topic definition lines in the text. The text can be entered first, and the EZhelp topic lines inserted later, or the topic lines can be entered first, and the text inserted between them. Topic lines include the name of the topic, the menu number, the order within the menu, and sub-topics to follow, if applicable. If there are no sub-topics to follow, the text following the topic line will be displayed. {{ Creating topics, 2,2,0 }}  Creating topics Working from your outline, you will create Topic Descriptions that will be displayed in the pop-up menus. The topic itself is a line of text that you will insert in your document, just above the point where the help text begins for that topic. The topic consists of: {{ topic name, menu #, menu order, next menu }}  {{ - double brackets placed in the text will begin a topic definition. A topic definition is ended with another set of brackets }}.  topic name - you may use up to fifteen characters for the topic, beginning with the first character at the left.  menu # - this will identify the group of topics which are to be shown on the same menu. The outermost menu, or most general, should begin with 1 as a rule.  menu order - this will specify the order of the topic among the other topics in the menu, from top to bottom. If you wish the menu topics to be sorted alphabetically, use 0 for the order number in each topic in the menu.  next menu - if this topic leads to another topic sub-menu, use the sub-menu number. If this topic leads to the help text (the help text follows the topic in the document), use 0. The topic which defined the text you are now reading is: {{ Creating topics, 2,2,0 }} Note that each parameter in the topic should be followed with a comma. The spacing between the parameters is not critical, but only numbers should be used for the last three. Menu numbers may be 1 - 256, although the maximum number of menu layers is 16. The topic definition must contain a complete set of brackets, parameters, and commas, or unexpected results may occur. Here is an example of a complete set of menu definitions for a help reference describing methods of transportation: {{ Land, 1, 1, 2 }} {{ Water, 1, 2, 3 }} menu 1, 3 topics {{ Air, 1, 3, 4 }} ____________________ {{ Car, 2, 1, 0 }} {{ Bicycle, 2, 2, 0 }} menu 2, 3 topics {{ Feet, 2, 3, 0 }} ____________________ {{ Speedboat, 3, 1, 0 }} {{ Yacht, 3, 2, 0 }} menu 3, 3 topics {{ Jet ski, 3, 3, 0 }} ____________________ {{ Airlines, 4, 1, 0 }} {{ Hang glider, 4, 2, 0 }} menu 4, 2 topics Note that menu in menu 1, topic "Land" defines a next menu, 2. Also in menu 1, topic "Water" defines next menu 3, and topic "Air" defines next menu 4. {{ Entering text, 2,3,0 }}  Entering text This is the basic layout of an EZhelp text file: 旼컴컴컴컴컴컴컴컴컴컴컴컴커 � .beginning of file � � � � Comments (a) � (a) Optional comments may be placed � � at the beginning of the file, until � Topic definition (b) � the first Topic definition. � � � Accompanying text (c) � (b) A topic definition line will � � always be followed with Accompanying � Topic definition (b) � text unless another menu is to � � follow. � Accompanying text (c) � � � (c) The accompanying text will be � Topic definition (b) � assumed to continue until the next � � topic definition is found, or the � Accompanying text (c) � end of the file is reached. � � � .end of file � 읕컴컴컴컴컴컴컴컴컴컴컴컴켸 An EZhelp text file MUST conform to these three guidelines:  Carriage return/line feed (CR/LF): A carriage return/line feed pair must terminate every line in the file. What this means for text written with many commercial word processors (Microsoft Word, Wordperfect, others) is that it will likely be neccessary to press the return key at the end of each line, rather than letting the line wrap around. One way to tell if your word processor generates the CR/LF at the end of each line is to use the DOS "TYPE" command to view the text file on the screen. If the text is not indented as you would see it in the word processor, then you will need to press return at the end of each line. Avoid using the tab key in the text. Instead, indent using the space bar. All other text formatting commands used by your word processor should be avoided also. If it is possible, save the file with your word processor in unformatted mode.  Line length: A line MUST be 74 characters or less. If the line is longer than 74 characters, unexpected results may occur. One common result is when the entire page shifts up by one line. Take care to follow this guideline.  Recompiling: The reference text file must be recompiled after each time it is modified. If it is not recompiled, the help text displays will overlap, and the topic definition line may be visible on the screen. {{ Files involved, 3,1,0 }}  Files involved "myfile.txt", when compiled, creates an index "myfile.hnx". 旼컴컴컴커 旼컴컴컴컴컴컴컴� 旼컴컴컴컴� � � � � � � � Text � -----> � EZcomp.exe � -----> � Text � � file � -----> � (compiler) � -----> � index � � � � � � � 읕컴컴컴켸 읕컴컴컴컴컴컴컴� 읕컴컴컴컴� The index file name is created using the first part of the text file name and adding ".hnx" as the extension. The index file will be placed in the same subdirectory as the text file. {{ Command line, 3,2,0 }}  Command line - EZcomp.exe Usage: EZcomp MYFILE.TXT [-pu] [-ps] From the DOS prompt, enter the following command to compile a help text file: EZcomp MYFILE.TXT The compiler runs for a moment, creates the index "myfile.hnx" using the text file "myfile.txt", and returns to the DOS prompt. To compile the text and print an unsorted report of the topics, enter this command: EZcomp MYFILE.TXT -pu To print a sorted report of the topics, substitute "-ps" on the command line, or include both "-pu" and "-ps" for both reports. {{ Reporting, 3,3,0 }}  Reporting Shown below is a sample report generated by EZcomp.exe. The report is printed once in the natural order that topic definitions are found in the text, and once in the sorted order that is used by EZhelp.exe. ---------------------------------------------------------------------- EZcomp v1.0 Reference Index report, unsorted: ezhelp.txt Page 1 ---------------------------------------------------------------------- Menu Menu Next Line Line number order Topic menu number count Offset Size ------ ----- --------------- ----- ------ ------ ------ ------ 1 1 What's EZhelp? 8 91 244 2753 1 2 3 easy steps 99 22 3025 462 1 3 Writing text 2 121 4 3515 35 1 4 Compiling text 3 125 4 3578 35 1 5 Using EZhelp 4 129 4 3641 35 1 6 Registering 133 70 3704 2928 1 7 --------------- 203 2 6660 4 1 8 Charityware? 205 24 6692 1177 {{ Memory needed, 4,1,0 }}  Memory needed EZhelp menus and help text windows allocate and release memory as they are used. The amount of memory required will depend on the size and levels of the menus. The program will have a pool of free memory to use in the size of (64k - size of ezhelp.exe). If there is no free memory to allocate, the program will display an error message and exit. {{ Files involved, 4,2,0 }}  Files involved 旼컴컴컴컴컴컴컴� 旼컴컴컴커 � � <----- � Text � � � <----- � index � � EZhelp.exe � 읕컴컴컴켸 � (help text � � driver) � 旼컴컴컴커 � � <----- � Text � � � <----- � file � 읕컴컴컴컴컴컴컴� 읕컴컴컴켸 EZhelp.exe uses the text file created with a word processor or text editor, and the index created from the text file with EZcomp.exe, to drive the displays of menus and help text. If the text file or text index is not found (as specified in the command line), EZhelp will display an error message and exit. {{ Command line, 4,3,0 }}  Command line - EZhelp.exe Usage: EZhelp MYFILE.TXT [-Mnnn -Jnnn -Bn -Snn -An -Dn -En -Ln ] MYFILE.TXT The name of a text reference file to be used. Up to 40 characters may be used for the full path and file name. The index MYFILE.HNX is assumed to reside in the same subdirectory. -Mnnn The number of the menu to start at. The program will begin by displaying the Topic descriptions for that menu, as defined in MYFILE.TXT. All subsequent menus from the point of the startup menu will be accessible. If none is specified, the default is 1. The maximum menu value possible is 255. -Jnnn The number of the topic in the start menu specified to display directly. If the -Jnn option is used, the menu will not be shown, and the help text for topic -Jnnn in menu -Mnnn will display. The maximum topic value possible is 255. -Bn A number to define the menu and help text window borders. There are four different choices, as shown below. The default is 1. 旼컴� 郞袴� �袴敲 靈컴� � 1 � � 2 � � 3 � � 4 � 읕컴� 突袴� 훤袴� 聃컴� -Snn A number to define the size (in lines) of the help text window display. The minimum window size is 4, and the maximum is 23. The default is 23 lines. --------------------------------------------------------------------- Override options - the next four options will override the default data file. To set the option ON, use 1. To set it OFF, use 0. --------------------------------------------------------------------- -An Automatic window sizing. -Dn If this option is selected, the page number of the reference will display at the lower left of the screen. -En This option will display error messages, should an error occur. -Ln This option will display text at the top or bottom of the screen. 1 = TOP, 0 = BOTTOM, default = 1. Examples: 1) EZhelp MYFILE.TXT Start MYFILE.TXT at menu 1, use all defaults. 2) EZhelp MYFILE.TXT -M4 -J7 -S15 Jump directly to the display of topic 7 in menu 4. Set the text display window to 15 lines. 3) EZhelp MYFILE.TXT -E1 -A1 -L1 Start MYFILE.TXT with error messages and automatic window sizing ON. Display text at the top of the screen. Note: The order of the specified options is not critical. {{ Examples, 4,3,90 }} .... menu 90 is next .... {{ Distribution, 4,5,0 }}  Distribution Unregistered and registered users may distribute copies of this package in its complete form, including EZhelp.exe, EZcomp.exe, EZsetup.exe, EZhelp.txt and EZhelp.hnx, and user's manual. We encourage you to do so. Registered users may bundle EZhelp.exe with their own applications and distribute unlimited copies. If a registered user distributes EZhelp.exe, the file name may not be changed. For more information on registering EZhelp, select the "Registering" topic. {{ Enhancments, 4,6,0 }}  Enhancements Here is a list of enhancements that are being considered for the next version of EZhelp. Variable length topics Page breaks embedded within the help text Override options within the help text Hypertext links to other topics in the reference window Help text printing Single-line scrolling If you have any suggestions for enhancements to this program, send us a postcard or letter. {{ ---------------, 4,7,0 }} {{ Quick summary, 4,8,0 }}  Quick summary of commands Topic definitions 컴컴컴컴컴컴컴컴컴컴컴컴� {{ topic name, menu #, menu order, next menu }} 1 - 15 chars all of the 0 for sort on 0 for display ended with a topics in topic name; text to follow; comma a menu have Other - use Other - display the same # order chosen the next menu Compiling 컴컴컴컴컴컴컴컴컴컴컴컴� EZcomp MYFILE.TXT [-pu] [-ps] Note: Use your own help text file in place of MYFILE.TXT. Use the -pu and -ps options to print a report on the text file topics, unsorted or sorted. Running EZhelp 컴컴컴컴컴컴컴컴컴컴컴컴� Usage: EZhelp MYFILE.TXT [-Mnnn -Jnnn -Bn -Snn -An -Dn -En -Ln ] {{ 1 more menu, 90,0,91 }} .... menu 91 is next .... {{ 2 aaaaaaaaaaaa, 90,0,0 }} {{ 3 aaaaaaaaaaaa, 90,0,0 }} {{ 4 aaaaaaaaaaaa, 90,0,0 }} {{ 5 aaaaaaaaaaaa, 90,0,0 }} {{ 6 aaaaaaaaaaaa, 90,0,0 }} {{ 7 aaaaaaaaaaaa, 90,0,0 }} {{ 8 aaaaaaaaaaaa, 90,0,0 }} {{ 9 aaaaaaaaaaaa, 90,0,0 }} {{ 10 aaaaaaaaaaa, 90,0,0 }} {{ 11 aaaaaaaaaaa, 90,0,0 }} {{ 12 aaaaaaaaaaa, 90,0,0 }} {{ 13 aaaaaaaaaaa, 90,0,0 }} {{ 14 aaaaaaaaaaa, 90,0,0 }} {{ 15 aaaaaaaaaaa, 90,0,0 }} {{ 16 aaaaaaaaaaa, 90,0,0 }} {{ 17 aaaaaaaaaaa, 90,0,0 }} {{ 18 aaaaaaaaaaa, 90,0,0 }} {{ 19 aaaaaaaaaaa, 90,0,0 }} {{ 20 aaaaaaaaaaa, 90,0,0 }} {{ 21 aaaaaaaaaaa, 90,0,0 }} {{ 22 aaaaaaaaaaa, 90,0,0 }} {{ 23 aaaaaaaaaaa, 90,0,0 }} {{ 24 aaaaaaaaaaa, 90,0,0 }} {{ 25 aaaaaaaaaaa, 90,0,0 }} {{ 26 aaaaaaaaaaa, 90,0,0 }} {{ 27 aaaaaaaaaaa, 90,0,0 }} {{ 28 aaaaaaaaaaa, 90,0,0 }} {{ 29 aaaaaaaaaaa, 90,0,0 }} {{ 30 aaaaaaaaaaa, 90,0,0 }} {{ 31 aaaaaaaaaaa, 90,0,0 }} {{ 32 aaaaaaaaaaa, 90,0,0 }} {{ 33 aaaaaaaaaaa, 90,0,0 }} {{ 34 aaaaaaaaaaa, 90,0,0 }} {{ 35 aaaaaaaaaaa, 90,0,0 }} {{ 36 aaaaaaaaaaa, 90,0,0 }} {{ 37 aaaaaaaaaaa, 90,0,0 }} {{ 38 aaaaaaaaaaa, 90,0,0 }} {{ 39 aaaaaaaaaaa, 90,0,0 }} {{ 40 aaaaaaaaaaa, 90,0,0 }} {{ 41 aaaaaaaaaaa, 90,0,0 }} {{ 42 aaaaaaaaaaa, 90,0,0 }} {{ 43 aaaaaaaaaaa, 90,0,0 }} {{ 44 aaaaaaaaaaa, 90,0,0 }} {{ 45 aaaaaaaaaaa, 90,0,0 }} {{ 46 aaaaaaaaaaa, 90,0,0 }} {{ 47 aaaaaaaaaaa, 90,0,0 }} {{ 48 aaaaaaaaaaa, 90,0,0 }} {{ 49 aaaaaaaaaaa, 90,0,0 }} {{ 50 aaaaaaaaaaa, 90,0,0 }} {{ 51 aaaaaaaaaaa, 90,0,0 }} {{ 52 aaaaaaaaaaa, 90,0,0 }} {{ 53 aaaaaaaaaaa, 90,0,0 }} {{ 54 aaaaaaaaaaa, 90,0,0 }} {{ 55 aaaaaaaaaaa, 90,0,0 }} {{ 56 aaaaaaaaaaa, 90,0,0 }} {{ 57 aaaaaaaaaaa, 90,0,0 }} {{ 58 aaaaaaaaaaa, 90,0,0 }} {{ 59 aaaaaaaaaaa, 90,0,0 }} {{ 60 aaaaaaaaaaa, 90,0,0 }} {{ 61 aaaaaaaaaaa, 90,0,0 }} {{ 62 aaaaaaaaaaa, 90,0,0 }} {{ 63 aaaaaaaaaaa, 90,0,0 }} {{ 64 aaaaaaaaaaa, 90,0,0 }} {{ 65 aaaaaaaaaaa, 90,0,0 }} {{ 66 aaaaaaaaaaa, 90,0,0 }} {{ 67 aaaaaaaaaaa, 90,0,0 }} {{ 68 aaaaaaaaaaa, 90,0,0 }} {{ 69 aaaaaaaaaaa, 90,0,0 }} {{ 1 more menu, 91,0,92 }} .... menu 92 is next .... {{ 2 bbbbbbbbbbbb, 91,0,0 }} {{ 3 bbbbbbbbbbbb, 91,0,0 }} {{ 4 bbbbbbbbbbbb, 91,0,0 }} {{ 5 bbbbbbbbbbbb, 91,0,0 }} {{ 6 bbbbbbbbbbbb, 91,0,0 }} {{ 7 bbbbbbbbbbbb, 91,0,0 }} {{ 1 cccccccccccc, 92,0,0 }} {{ 2 cccccccccccc, 92,0,0 }} {{ 3 cccccccccccc, 92,0,0 }} {{ 4 cccccccccccc, 92,0,0 }} {{ 5 cccccccccccc, 92,0,0 }} {{ 6 cccccccccccc, 92,0,0 }} {{ 7 cccccccccccc, 92,0,0 }} {{ 8 cccccccccccc, 92,0,0 }} {{ 9 cccccccccccc, 92,0,0 }} {{ 10 ccccccccccc, 92,0,0 }} {{ 11 ccccccccccc, 92,0,0 }} {{ 12 ccccccccccc, 92,0,0 }} {{ 13 ccccccccccc, 92,0,0 }} {{ 14 ccccccccccc, 92,0,0 }} {{ 15 ccccccccccc, 92,0,0 }} {{ 16 ccccccccccc, 92,0,0 }} {{ 17 ccccccccccc, 92,0,0 }} {{ 18 ccccccccccc, 92,0,0 }} {{ 19 ccccccccccc, 92,0,0 }} {{ 20 ccccccccccc, 92,0,0 }} {{ 21 ccccccccccc, 92,0,0 }} {{ 22 ccccccccccc, 92,0,0 }} {{ 23 ccccccccccc, 92,0,0 }} {{ 24 ccccccccccc, 92,0,0 }} {{ 25 ccccccccccc, 92,0,0 }} {{ 26 ccccccccccc, 92,0,0 }} {{ 27 ccccccccccc, 92,0,0 }} {{ 28 ccccccccccc, 92,0,0 }} {{ 29 ccccccccccc, 92,0,0 }} {{ 30 ccccccccccc, 92,0,0 }} {{ 31 ccccccccccc, 92,0,0 }} {{ 32 ccccccccccc, 92,0,0 }} {{ 33 ccccccccccc, 92,0,0 }} {{ 34 ccccccccccc, 92,0,0 }} {{ 35 ccccccccccc, 92,0,0 }}